<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Documentation File Formatting - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/doc-standard.file-formatting.html">Inglês (English)</a></li>
    <li><a href="../pt-br/doc-standard.file-formatting.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.overview.html">Overview</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="doc-standard.recommendations.html">Recommendations</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="doc-standard.file-formatting" class="section"><div class="info"><h1 class="title">Documentation File Formatting</h1></div>
        

        <div class="section" id="doc-standard.file-formatting.xml-tags"><div class="info"><h1 class="title">XML Tags</h1></div>
            

            <p class="para">
                Each manual file must include the following <acronym class="acronym">XML</acronym> declarations at
                the top of the file:
            </p>

            <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!-- Reviewed: no --&gt;
</pre>


            <p class="para">
                <acronym class="acronym">XML</acronym> files from translated languages must also include a revision
                tag containing the revision of the corresponding English-language file the
                translation was based on.
            </p>

            <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!-- EN-Revision: 14978 --&gt;
&lt;!-- Reviewed: no --&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.max-line-length"><div class="info"><h1 class="title">Maximum Line Length</h1></div>
            

            <p class="para">
                The maximum line length, including tags, attributes, and indentation, is not to
                exceed 100 characters. There is only one exception to this rule: attribute and value
                pairs are allowed to exceed the 100 chars as they are not allowed to be separated.
            </p>
        </div>

        <div class="section" id="doc-standard.file-formatting.indentation"><div class="info"><h1 class="title">Indentation</h1></div>
            

            <p class="para">Indentation should consist of 4 spaces. Tabs are not allowed.</p>
            <p class="para">Tags which are at the same level must have the same indentation.</p>

            <pre class="programlisting brush: xml">
&lt;sect1&gt;
&lt;/sect1&gt;

&lt;sect1&gt;
&lt;/sect1&gt;
</pre>


            <p class="para">
                Tags which are one level under the previous tag must be indented with 4 additional
                spaces.
            </p>

            <pre class="programlisting brush: xml">
&lt;sect1&gt;
    &lt;sect2&gt;
    &lt;/sect2&gt;
&lt;/sect1&gt;
</pre>


            <p class="para">
                Multiple block tags within the same line are not allowed; multiple inline tags are
                allowed, however.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED: --&gt;
&lt;sect1&gt;&lt;sect2&gt;
&lt;/sect2&gt;&lt;/sect1&gt;

&lt;!-- ALLOWED --&gt;
&lt;para&gt;
    &lt;classname&gt;Zend_Magic&lt;/classname&gt; does not exist. &lt;classname&gt;Zend_Acl&lt;/classname&gt; does.
&lt;/para&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.line-termination"><div class="info"><h1 class="title">Line Termination</h1></div>
            

            <p class="para">
                Line termination follows the Unix text file convention. Lines must end with a
                single linefeed (LF) character. Linefeed characters are represented as ordinal 10,
                or hexadecimal 0x0A.
            </p>

            <p class="para">
                Note: Do not use carriage returns (<acronym class="acronym">CR</acronym>) as is the convention in
                Apple OS&#039;s (0x0D) or the carriage return - linefeed combination
                (<acronym class="acronym">CRLF</acronym>) as is standard for the Windows OS (0x0D, 0x0A).
            </p>
        </div>

        <div class="section" id="doc-standard.file-formatting.empty-tags"><div class="info"><h1 class="title">Empty tags</h1></div>
            

            <p class="para">
                Empty tags are not allowed; all tags must contain text or child tags.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;para&gt;
    Some text. &lt;link&gt;&lt;/link&gt;
&lt;/para&gt;

&lt;para&gt;
&lt;/para&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.whitespace"><div class="info"><h1 class="title">Usage of whitespace within documents</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.whitespace.trailing"><div class="info"><h1 class="title">Whitespace within tags</h1></div>
                

                <p class="para">
                    Opening block tags should have no whitespace immediately following them other
                    than line breaks (and indentation on the following line).
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;sect1&gt;WHITESPACE
&lt;/sect1&gt;
</pre>


                <p class="para">
                    Opening inline tags should have no whitespace immediately following them.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
This is the class &lt;classname&gt; Zend_Class&lt;/classname&gt;.

&lt;!-- OK --&gt;
This is the class &lt;classname&gt;Zend_Class&lt;/classname&gt;.
</pre>


                <p class="para">
                    Closing block tags may be preceded by whitespace equivalent to the current
                    indentation level, but no more than that amount.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
    &lt;sect1&gt;
     &lt;/sect1&gt;

&lt;!-- OK --&gt;
    &lt;sect1&gt;
    &lt;/sect1&gt;
</pre>


                <p class="para">
                    Closing inline tags must not be preceded by any whitespace.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
This is the class &lt;classname&gt;Zend_Class &lt;/classname&gt;

&lt;!-- OK --&gt;
This is the class &lt;classname&gt;Zend_Class&lt;/classname&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.whitespace.multiple-line-breaks"><div class="info"><h1 class="title">Multiple line breaks</h1></div>
                

                <p class="para">
                    Multiple line breaks within or between tags are not allowed.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;para&gt;
    Some text...

    ... and more text
&lt;/para&gt;


&lt;para&gt;
    Another paragraph.
&lt;/para&gt;

&lt;!-- OK --&gt;
&lt;para&gt;
    Some text...
    ... and more text
&lt;/para&gt;

&lt;para&gt;
    Another paragraph.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.whitespace.tag-separation"><div class="info"><h1 class="title">Separation between tags</h1></div>
                

                <p class="para">
                    Tags at the same level must be separated by an empty line to improve
                    readability.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;para&gt;
    Some text...
&lt;/para&gt;
&lt;para&gt;
    More text...
&lt;/para&gt;

&lt;!-- OK --&gt;
&lt;para&gt;
    Some text...
&lt;/para&gt;

&lt;para&gt;
    More text...
&lt;/para&gt;
</pre>


                <p class="para">
                    The first child tag should open directly below its parent, with no empty line
                    between them; the last child tag should close directly before the closing tag of
                    its parent.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;sect1&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

&lt;/sect1&gt;

&lt;!-- OK --&gt;
&lt;sect1&gt;
    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;
&lt;/sect1&gt;
</pre>

            </div>
        </div>

        <div class="section" id="doc-standard.file-formatting.program-listing"><div class="info"><h1 class="title">Program Listings</h1></div>
            

            <p class="para">
                The opening <em class="emphasis">&lt;programlisting&gt;</em> tag must indicate the
                appropriate &quot;language&quot; attribute and be indented at the same level as its sibling
                blocks.
            </p>

            <pre class="programlisting brush: xml">
&lt;para&gt;Sibling paragraph.&lt;/para&gt;

&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
</pre>


            <p class="para">
                <acronym class="acronym">CDATA</acronym> should be used around all program listings.
            </p>

            <p class="para">
                <em class="emphasis">&lt;programlisting&gt;</em> sections must not add linebreaks or
                whitespace at the beginning or end of the section, as these are then represented in
                the final output.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[

$render = &quot;xxx&quot;;

]]&gt;&lt;/programlisting&gt;

&lt;!-- OK --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                Ending <acronym class="acronym">CDATA</acronym> and <em class="emphasis">&lt;programlisting&gt;</em>
                tags should be on the same line, without any indentation.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;
    &lt;/programlisting&gt;

&lt;!-- NOT ALLOWED --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
    ]]&gt;&lt;/programlisting&gt;

&lt;!-- OK --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                The <em class="emphasis">&lt;programlisting&gt;</em> tag should contain the &quot;language&quot;
                attribute with a value appropriate to the contents of the program listing. Typical
                values include &quot;css&quot;, &quot;html&quot;, &quot;ini&quot;, &quot;javascript&quot;, &quot;php&quot;, &quot;text&quot;, and &quot;xml&quot;.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- PHP --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[

&lt;!-- Javascript --&gt;
&lt;programlisting language=&quot;javascript&quot;&gt;&lt;![CDATA[

&lt;!-- XML --&gt;
&lt;programlisting language=&quot;xml&quot;&gt;&lt;![CDATA[
</pre>


            <p class="para">
                For program listings containing only <acronym class="acronym">PHP</acronym> code,
                <acronym class="acronym">PHP</acronym> tags (e.g., &quot;&lt;?php&quot;, &quot;?&gt;&quot;) are not required, and
                should not be used. They simply clutter the narrative, and are implied by the use
                of the <em class="emphasis">&lt;programlisting&gt;</em> tag.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;programlisting language=&quot;php&quot;&lt;![CDATA[&lt;?php
    // ...
?&gt;]]&gt;&lt;/programlisting&gt;

&lt;programlisting language=&quot;php&quot;&lt;![CDATA[
&lt;?php
    // ...
?&gt;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                Line lengths within program listings should follow the <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.max-line-length" class="link">coding standards
                recommendations</a>.
            </p>

            <p class="para">
                Refrain from using  <span class="methodname">require_once()</span>,
                 <span class="methodname">require()</span>,  <span class="methodname">include_once()</span>, and
                 <span class="methodname">include()</span> calls within <acronym class="acronym">PHP</acronym> listings.
                They simply clutter the narrative, and are largely obviated when using an
                autoloader. Use them only when they are essential to the example.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Never use short tags</b><br /></span>
                

                <p class="para">
                    Short tags (e.g., &quot;&lt;?&quot;, &quot;&lt;?=&quot;) should never be used within
                    <em class="emphasis">programlisting</em> or the narrative of a document.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="doc-standard.file-formatting.inline-tags"><div class="info"><h1 class="title">Notes on specific inline tags</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.inline-tags.classname"><div class="info"><h1 class="title">classname</h1></div>
                

                <p class="para">
                    The tag <em class="emphasis">&lt;classname&gt;</em> must be used each time a class
                    name is represented by itself; it should not be used when combined with a
                    method name, variable name, or constant, and no other content is allowed within
                    the tag.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    The class &lt;classname&gt;Zend_Class&lt;/classname&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.varname"><div class="info"><h1 class="title">varname</h1></div>
                

                <p class="para">
                    Variables must be wrapped in the <em class="emphasis">&lt;varname&gt;</em> tag.
                    Variables must be written using the &quot;$&quot; sigil. No other content is allowed
                    within this tag, unless a class name is used, which indicates a class variable.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    The variable &lt;varname&gt;$var&lt;/varname&gt; and the class variable
    &lt;varname&gt;Zend_Class::$var&lt;/varname&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.methodname"><div class="info"><h1 class="title">methodname</h1></div>
                

                <p class="para">
                    Methods must be wrapped in the <em class="emphasis">&lt;methodname&gt;</em> tag.
                    Methods must either include the full method signature or at the least a pair of
                    closing parentheses (e.g., &quot;()&quot;). No other content is allowed within this tag,
                    unless a class name is used, which indicates a class method.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    The method &lt;methodname&gt;foo()&lt;/methodname&gt; and the class method
    &lt;methodname&gt;Zend_Class::foo()&lt;/methodname&gt;. A method with a full signature:
    &lt;methodname&gt;foo($bar, $baz)&lt;/methodname&gt;
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.constant"><div class="info"><h1 class="title">constant</h1></div>
                

                <p class="para">
                    Use the <em class="emphasis">&lt;constant&gt;</em> tag when denoting constants.
                    Constants must be written in <acronym class="acronym">UPPERCASE</acronym>. No other content is
                    allowed within this tag, unless a class name is used, which indicates a class
                    constant.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    The constant &lt;constant&gt;FOO&lt;/constant&gt; and the class constant
    &lt;constant&gt;Zend_Class::FOO&lt;/constant&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.filename"><div class="info"><h1 class="title">filename</h1></div>
                

                <p class="para">
                    Filenames and paths must be wrapped in the
                    <em class="emphasis">&lt;filename&gt;</em> tag. No other content is allowed in this
                    tag.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    The filename &lt;filename&gt;application/Bootstrap.php&lt;/filename&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.command"><div class="info"><h1 class="title">command</h1></div>
                

                <p class="para">
                    Commands, shell scripts, and program calls must be wrapped in the
                    <em class="emphasis">&lt;command&gt;</em> tag. If the command includes arguments,
                    these should also be included within the tag.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    Execute &lt;command&gt;zf.sh create project&lt;/command&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.code"><div class="info"><h1 class="title">code</h1></div>
                

                <p class="para">
                    Usage of the <em class="emphasis">&lt;code&gt;</em> tag is discouraged, in favor of
                    the other inline tasks discussed previously.
                </p>
            </div>
        </div>

        <div class="section" id="doc-standard.file-formatting.block-tags"><div class="info"><h1 class="title">Notes on specific block tags</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.block-tags.title"><div class="info"><h1 class="title">title</h1></div>
                

                <p class="para">
                    The <em class="emphasis">&lt;title&gt;</em> tag is not allowed to hold other tags.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NOT ALLOWED --&gt;
&lt;title&gt;Using &lt;classname&gt;Zend_Class&lt;/classname&gt;&lt;/title&gt;

&lt;!-- OK --&gt;
&lt;title&gt;Using Zend_Class&lt;/title&gt;
</pre>

            </div>
        </div>
    </div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.overview.html">Overview</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="doc-standard.recommendations.html">Recommendations</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></li>
  <li><a href="doc-standard.overview.html">Overview</a></li>
  <li class="active"><a href="doc-standard.file-formatting.html">Documentation File Formatting</a></li>
  <li><a href="doc-standard.recommendations.html">Recommendations</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>